home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / strg61a.arc / STRG61A.DOC < prev    next >
Text File  |  1991-01-22  |  40KB  |  1,181 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.                               STRG STRING UTILITIES
  20.                                   USER'S GUIDE
  21.  
  22.                                   Version 6.1a
  23.                                 January 23, 1991
  24.  
  25.  
  26.                Copyright (C) 1989-1991 Eagle Performance Software
  27.                               All Rights Reserved.
  28.  
  29.  
  30.  
  31.                                _______                     
  32.                           ____| _     |               (tm) 
  33.                        --|       |    |------------------- 
  34.                          |   ____|__  |  Association of    
  35.                          |  |       |_|  Shareware         
  36.                          |__|   o   |    Professionals     
  37.                        -----|   |   |--------------------- 
  38.                             |___|___|    MEMBER            
  39.  
  40.  
  41.    STRG String Utilities                           User's Guide, Version 6.1a
  42.  
  43.  
  44.  
  45.                        T A B L E   O F   C O N T E N T S
  46.  
  47.         1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 3
  48.              Features  . . . . . . . . . . . . . . . . . . . . . . 3
  49.              Using the Manuals . . . . . . . . . . . . . . . . . . 3
  50.              Licensing . . . . . . . . . . . . . . . . . . . . . . 4
  51.              Customer Service  . . . . . . . . . . . . . . . . . . 4
  52.              ASP . . . . . . . . . . . . . . . . . . . . . . . . . 4
  53.  
  54.         2. GETTING STARTED . . . . . . . . . . . . . . . . . . . . 6
  55.              Distribution Files  . . . . . . . . . . . . . . . . . 6
  56.              Simple Programming  . . . . . . . . . . . . . . . . . 6
  57.              Procedures and Functions  . . . . . . . . . . . . . . 6
  58.  
  59.         3. PHILOSOPHY  . . . . . . . . . . . . . . . . . . . . . . 11
  60.              Unit Design . . . . . . . . . . . . . . . . . . . . . 11
  61.              Program Design  . . . . . . . . . . . . . . . . . . . 11
  62.              Number to String Conversion . . . . . . . . . . . . . 14
  63.              Null String Interpretation  . . . . . . . . . . . . . 14
  64.              Greater Speeds  . . . . . . . . . . . . . . . . . . . 15
  65.  
  66.         APPENDIX A: Other Products . . . . . . . . . . . . . . . . 16
  67.  
  68.         APPENDIX B: Revision History . . . . . . . . . . . . . . . 19
  69.  
  70.         APPENDIX C: References . . . . . . . . . . . . . . . . . . 20
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.                                        2
  101.    STRG String Utilities                           User's Guide, Version 6.1a
  102.  
  103.  
  104.    1.  I N T R O D U C T I O N
  105.  
  106.  
  107.    FEATURES
  108.  
  109.    Welcome to STRG String Utilities!  
  110.  
  111.    You have just obtained a copy of the highest performance string processing 
  112.    routines available today for Turbo Pascal 6.0 (TP6).  Both novice and 
  113.    professional programmers will appreciate these simple and very powerful 
  114.    utilities that gives you ultimate speed for string-intensive programs.
  115.    
  116.    Here are some of the features you will discover:
  117.  
  118.      . Extremely-high speed techniques have been used to create 
  119.        the fastest processing possible.
  120. |    . 111 routines process strings, characters, and all types of 
  121.        numbers.  Several combinations of operations have been 
  122.        provided that are extremely fast for case, classification, 
  123.        comparison, conversions, copy, count, delete, format, 
  124.        justification, membership, parse, replace, search, sort, 
  125.        tabbing, ASCIIZ, many with match/ignore case and many 
  126.        more.
  127.      . Uses many of the same identifiers as C standard routines.
  128.      . Much faster than Pascal and C standard routines.
  129.      . Easy to remember routine identifiers.
  130.      . Source code compiles in either Turbo Pascal or 
  131.        QuickPascal.
  132. |    . Only 6.3k bytes of code if all 111 routines are used.
  133.      . Optimized by the compiler and drops unused code.
  134.      . Used in all other Eagle products.
  135.  
  136.  
  137.    USING THE MANUALS
  138.  
  139.    Disk Based Guides - The manuals for STRG are on disk so that you can 
  140.    conveniently scan for the topic you are seeking.  You can do this with any 
  141.    list or search utility with a search function.  You can also make a printed 
  142.    copy.  If you have not already printed this manual, refer to the 
  143.    TOPRINT.TXT file for instructions.  At the present time, no bound manuals 
  144. |  are being offered with registration, but this may change soon.
  145.  
  146.    User's Guide - This manual, the one your are reading now, assumes that as a 
  147.    programmer you are already familiar with Pascal and that you have a working 
  148.    knowledge of your disk operating system (DOS).  It will provide you the 
  149.    judgment and techniques for faster text processing.
  150.  
  151.    Reference Guide - This manual describes in detail all procedures, functions 
  152.    and variables used in STRG.  It is alphabetically arranged for easy access 
  153.    in a format similar to the compiler reference manual.  Use this manual when 
  154.    you have become familiar with the basic principles in the user's guide.
  155.  
  156.  
  157.  
  158.  
  159.  
  160.    Chapter 1, Introduction                                             Page 3
  161.    STRG String Utilities                           User's Guide, Version 6.1a
  162.  
  163.  
  164.    LICENSING
  165.  
  166.    Registration - These utilities and the documentation have been released for 
  167.    distribution as Shareware.  You have been given the chance to sample the 
  168.    full capability of STRG without risk!  If you find that STRG is a valuable 
  169.    tool, then you are expected to register.  You will find a reasonable 
  170.    licensing schedule found in LICENSE.LIC to meet private or commercial 
  171.    needs.  When registering, be sure to specify the compiler and version you 
  172.    you are using.
  173.  
  174.    Source Code - All registered users will receive source code when the signed 
  175.    license agreement is returned with the registration.
  176.  
  177.  
  178.    CUSTOMER SERVICE
  179.  
  180.    If you have questions, comments, or suggestions, the Eagle can be contacted 
  181.    by four means - (1) CompuServe, (2) telephone, (3) The Eagle BBS, or 
  182.    (4) mail.
  183.  
  184.    CompuServe - The most dependable way to contact the Eagle is through 
  185. |  CompuServe.  For personal contact, Jordan Gallagher can be reached on the 
  186. |  Borland Forum by typing GO BPROGA from the CompuServe main menu to enter 
  187.    the Forum for Turbo Pascal.  You can contact Jordan with his PPN number of 
  188.    73557,2342.  Messages can also be left through CIS Mail.
  189.  
  190.    Telephone - Jordan can also be reached by phone at (214) 539-7855 on 
  191.    weekdays and Saturday from 9:00 a.m. to 8:00 p.m CST.
  192.  
  193.    The Eagle BBS - You can also contact us on our 24-hour BBS at (214) 539-
  194. |  9878, 1200/2400 N81.  Connections at 9600 V.42bis will be available soon.
  195.  
  196.    Mail - For registration or problems, please write:
  197.  
  198.        Eagle Performance Software
  199.        P.O. Box 292786
  200.        Lewisville, TX  75029-2786
  201.  
  202.    In your written request for resolving problems, be sure to include:
  203.  
  204.      . A diskette of compilable source code of the problem.
  205.      . The Eagle product and version number.
  206.      . The computer make and model.
  207.  
  208.  
  209.    ASP
  210.  
  211.    STRG is a shareware program conforming to the standards of the Association 
  212.    of Shareware Professionals (ASP).  You can get more information about ASP 
  213.    by writing to:
  214.     
  215.      Association of Shareware Professionals
  216.      P.O. Box 5786
  217.      Bellevue,WA 98006
  218.  
  219.  
  220.    Chapter 1, Introduction                                             Page 4
  221.    STRG String Utilities                           User's Guide, Version 6.1a
  222.  
  223.  
  224.  
  225.    This program is produced by a member of the Association of Shareware 
  226.    Professionals (ASP).  ASP wants to make sure that the shareware principle 
  227.    works for you.  If you are unable to resolve a shareware-related problem 
  228.    with an ASP member by contacting the member directly, ASP may be able to 
  229.    help.  The ASP Ombudsman can help you resolve a dispute or problem with an 
  230.    ASP member, but does not provide technical support for member's products.  
  231.    Please write to:
  232.  
  233.      ASP Ombudsman
  234.      P.O. Box 5786
  235.      Bellevue,WA 98006
  236.  
  237.    or send a CompuServe message via EasyPlex to ASP Ombudsman 7007,3536.
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.    Chapter 1, Introduction                                             Page 5
  281.    STRG String Utilities                           User's Guide, Version 6.1a
  282.  
  283.  
  284.    2.  G E T T I N G   S T A R T E D
  285.  
  286.    This section will acquaint you with the files on disk and show you a 
  287.    brief demonstration.  You will also run your first program with STRG and 
  288.    then become familiar with all of the utilities.
  289.  
  290.  
  291.    DISTRIBUTION FILES
  292.  
  293.    In this version, STRG61A.ZIP contains:
  294.  
  295.      Strg61a .tpu:  Compiled unit of 5900 lines of assembly for TP6.
  296.      Strg61a-.pas:  Partial source code for STRG61A.TPU.  (MASM source 
  297.                     code and object files are not included.)
  298.      Strg61a .doc:  This document - a user's guide to STRG.
  299.      StrgRef .doc:  STRG Reference Guide document covering each 
  300.                     procedure and variable in detail.
  301.      Rate61  .pas:  High-precision timer to test speed of routines.
  302.      ToPrint .txt:  Instructions for printing docs from DOS.
  303.      License .lic:  Order form.
  304.      Statment.lic:  Statement for license terms and conditions.
  305.  
  306. |  Files have been archived using PKZIP.  They should be authentically 
  307. |  verified after extraction with our company name -  Eagle Performance 
  308. |  Software.
  309.  
  310.  
  311.    SIMPLE PROGRAMMING
  312.  
  313.    First Program - Let's write a short program to see how simple it is to 
  314.    write with STRG.  First, do the following steps:
  315.  
  316.      1. Copy STRG61A.TPU to STRG.TPU for the compiler.
  317.      2. While in the compiler editor, enter the following code:
  318.  
  319.         {$E+,N+}
  320.         uses Crt,Strg;
  321.         var s1,s2: string;
  322.         begin
  323.           s1 := '(c) 1991 Eagle Performance Software';
  324.           StrUpr (s1);
  325.         end.
  326.  
  327.    Assuming you have already copied STRG61A.TPU to STRG.TPU, compile and run 
  328.    the code.  Using the watch window, check out the value of s1 and see that 
  329.    it is now completely upper case which is what the StrUpr procedure does.  
  330.    The StrUpr identifier may already be familiar to you - it is the same one 
  331.    used in C.  Many of the identifiers used in the STRG unit use identifiers 
  332.    that are similar in C, and using the same principles, other names were also 
  333.    created.
  334.  
  335.  
  336.    PROCEDURES AND FUNCTIONS
  337.  
  338.  
  339.  
  340.    Chapter 2, Getting Started                                          Page 6
  341.    STRG String Utilities                           User's Guide, Version 6.1a
  342.  
  343.  
  344.    STRG has many routines and are all described in detail in the reference 
  345.    manual.  But to get a full scope of the routines available, here is a 
  346.    brief survey of all the utilities arranged by application:
  347.  
  348.    Operations - These procedures operate directly on the characters in the 
  349.    string:
  350.  
  351.       StrLwr    - convert to lower case.
  352.       StrUpr    - convert to upper case.
  353.       StrRev    - reverses order of characters.
  354.       StrRoll   - rolls characters left or right.
  355.       StrSort   - sorts characters in ascending order.
  356.  
  357.    Insert and Delete - These procedures provide different methods for 
  358.    inserting or delete substrings or characters:
  359.  
  360.       ChrDel    - deletes all occurrences of a given character.
  361.       ChrDelL   - deletes all leading (Left) characters.
  362.       ChrDelR   - deletes all trailing (Right) characters.
  363.       ChrPadC   - pads characters left and right to center the field.
  364.       ChrPadL   - pads leading (Left) characters to fit in a field.
  365.       ChrPadR   - pads trailing (Right) characters to fit in a field.
  366.       StrCut    - truncates strings over a given length.
  367.       StrIns    - inserts a substring.
  368.  
  369.    Placement - These procedures efficiently place strings in memory with a 
  370.    single copy.
  371.  
  372.       StrCat    - appends one string with another.
  373.       StrCatX   - appends one string with a substring of another.
  374.       StrCopy   - copies a substring to create a new string.
  375.       StrMove   - simple string move.
  376.       StrOver   - overwrites a string at a given index with another substring 
  377.                   and fills any gap with spaces.
  378.       StrPeek   - copies an array from memory into a string.
  379.       StrPoke   - copies a string as an array without the length byte.
  380.  
  381.    Patterns - These procedures create strings with repetitive patterns:
  382.  
  383.       StrFill   - fills a string with duplicate copies of a substring or 
  384.                   character.
  385.       ChrFill   - fills a string with duplicate copies of a character.
  386.       StrEnum   - enumerates a string of characters in ascending or descending 
  387.                   order.
  388.  
  389.    Position - These procedures find the position of a character using 
  390.    different strategies:
  391.  
  392.       ChrPosL   - finds the Nth occurrence from the LEFT.
  393.       ChrPosLI  - finds the Nth occurrence from the LEFT ignoring case.
  394.       ChrPosR   - finds the Nth occurrence from the RIGHT.
  395.       ChrPosRI  - finds the Nth occurrence from the RIGHT ignoring case.
  396.       ChrPosX   - finds the first occurrence from the LEFT starting at indeX.
  397.       ChrPosXI  - finds the first occurrence from the LEFT starting at indeX 
  398.  
  399.  
  400.    Chapter 2, Getting Started                                          Page 7
  401.    STRG String Utilities                           User's Guide, Version 6.1a
  402.  
  403.  
  404.                   and ignoring case.
  405.  
  406.    Similar to the above procedures, these find the position of a substring or 
  407.    character using different strategies:
  408.  
  409.       StrPosL   - finds the Nth occurrence from the LEFT.
  410.       StrPosLI  - finds the Nth occurrence from the LEFT ignoring case.
  411.       StrPosR   - finds the Nth occurrence from the RIGHT.
  412.       StrPosRI  - finds the Nth occurrence from the RIGHT ignoring case.
  413.       StrPosX   - finds the first occurrence from the LEFT starting at indeX.
  414.       StrPosXI  - finds the first occurrence from the LEFT starting at indeX 
  415.                   and ignoring case.
  416.  
  417.    Quantity - These procedures find the total count of a given character or 
  418.    substring in a string:
  419.  
  420.       ChrQty    - count of a given character.
  421.       ChrQtyI   - count of a given character ignoring case.
  422.       StrQty    - count of a given substring.
  423.       StrQtyI   - count of a given substring ignoring case.
  424.  
  425.    Comparison - These procedures compare two substrings for greater than, less 
  426.    than, or equal result.  The optional indexes can also be obtained:
  427.  
  428.       StrCmp  - compares two substrings matching case.
  429.       StrCmpI - compares two substrings ignoring case.
  430.  
  431.    Find and Replace - These procedures find a given character or substring in 
  432.    a string and replace it with another.
  433.  
  434.       ChrRepl  - find and replace a character matching case.
  435.       ChrReplI - find and replace a character ignoring case.
  436.       StrRepl  - find and replace a character or substring matching case.
  437.       StrReplI - find and replace a character or substring ignoring case.
  438.  
  439.    Membership - These procedures search membership or non-membership in a 
  440.    string:
  441.  
  442.       StrBrk    - finds the first character that is a member.
  443.       StrSpn    - finds the first character that is not a member and returns 
  444.                   the span of membership.
  445.       StrMemb   - reduces a string to individual membership in ascending 
  446.                   order.
  447.  
  448.    Parsing - These routines find words separated by spaces:
  449.  
  450.       WrdQty    - counts the number of words in a string.
  451.       WrdPosL   - finds the Nth word from the LEFT.
  452.       WrdPosR   - finds the Nth word from the RIGHT.
  453.       WrdPosLX  - finds the Nth word from the LEFT starting at indeX.
  454.       WrdPosRX  - finds the Nth word from the RIGHT starting at indeX.
  455.       WrdL      - parses the Nth word from the LEFT.                   
  456.       WrdR      - parses the Nth word from the RIGHT.                  
  457.       WrdLX     - parses the Nth word from the LEFT starting at indeX. 
  458.  
  459.  
  460.    Chapter 2, Getting Started                                          Page 8
  461.    STRG String Utilities                           User's Guide, Version 6.1a
  462.  
  463.  
  464.       WrdRX     - parses the Nth word from the RIGHT starting at indeX.
  465.       WrdParse  - generic parsing routine parses a word between any two 
  466.                   delimiters.
  467.       WrdToken  - generic parsing routine parses a word between any two groups 
  468.                   of delimiters.
  469.  
  470.    Conversion - These routines convert numbers and strings into other common 
  471.    forms:
  472.  
  473.       StrHex    - converts scalars into hex strings.
  474.       StrBin    - converts scalars into binary strings.
  475.       ValBin    - converts binary strings into scalars.
  476.       ValHex    - converts hex strings into scalars.
  477.       StrDeTab  - expands tabs into spaces.
  478.       StrReTab  - reduces spaces into tabs.
  479.       AscStr    - converts strings into ASCIIZ strings.
  480.       LnStr     - converts strings into ASCII text strings.
  481.       StrAsc    - converts ASCIIZ strings into Pascal strings.
  482.       StrLn     - converts ASCII text strings into Pascal strings.
  483.  
  484.    Justification - These functions justify strings with spaces:
  485.  
  486.       StrJC     - Center justification
  487.       StrJL     - Left   justification
  488.       StrJR     - Right  justification
  489.  
  490.    Case - Just for characters, these functions change case and are faster than 
  491.    the System.Upcase in standard Pascal:
  492.  
  493.       LoCase    - Converts to lower case
  494.       UpCase    - Converts to upper case
  495.  
  496.    Classification - These boolean functions classify characters within a given 
  497.    group in the lower ASCII table (<#128):
  498.  
  499.       IsAlNum   - alpha-numeric
  500.       IsAlpha   - alphabetic
  501.       IsASCII   - lower ASCII table
  502.       IsCntrl   - printer control character
  503.       IsDigit   - numbers zero through nine
  504.       IsDOS     - DOS directory character
  505.       IsFile    - DOS file name character
  506.       IsGraph   - a "black" printable character
  507.       IsLower   - lower case
  508.       IsPath    - DOS drive, path, and file name character
  509.       IsPrint   - printable character
  510.       IsPunct   - punctuation character
  511.       IsReal    - real number character
  512.       IsSigned  - signed number
  513.       IsSpace   - non-printing paper-movement character
  514.       IsUpper   - upper case
  515.       IsXDigit  - hex digit
  516.  
  517.    Standard - As a bonus, automatic replacements of the Pascal standard 
  518.  
  519.  
  520.    Chapter 2, Getting Started                                          Page 9
  521.    STRG String Utilities                           User's Guide, Version 6.1a
  522.  
  523.  
  524.    routines are included:
  525.  
  526. |     Copy      - copies a substring up to 35% faster.
  527.       Delete    - deletes a substring up to 5 times faster.
  528. |     Pos       - finds the position of a substring up to 340% faster.
  529.  
  530.    Str Function Forms - As another bonus, function forms of the standard Str 
  531. |  procedure are provided for convenience.  They have a tad more overhead in 
  532. |  speed, but save code in the long run.
  533.  
  534.       StrC      - converts Comp to string
  535.       StrCF     - converts Comp to string in a fixed Field
  536.       StrCFD    - converts Comp to string in a fixed Field with a specified 
  537.                   number of Decimals
  538.       StrD      - converts Double to string
  539.       StrDF     - converts Double to string in a fixed Field
  540.       StrDFD    - converts Double to string in a fixed Field with a specified 
  541.                   number of Decimals
  542.       StrE      - converts Extended to string
  543.       StrEF     - converts Extended to string in a fixed Field
  544.       StrEFD    - converts Extended to string in a fixed Field with a 
  545.                   specified number of Decimals
  546.       StrL      - converts LongInt to string
  547.       StrLF     - converts LongInt to string in a fixed Field
  548.       StrR      - converts Real to string
  549.       StrRF     - converts Real to string in a fixed Field
  550.       StrRFD    - converts Real to string in a fixed Field with a specified 
  551.                   number of Decimals
  552.       StrS      - converts Single to string
  553.       StrSF     - converts Single to string in a fixed Field
  554.       StrSFD    - converts Single to string in a fixed Field with a specified 
  555.                   number of Decimals
  556.  
  557.    For a full description of each routine with its parameters, please refer to 
  558.    STRGREF.DOC for a summary of details and examples.
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.    Chapter 2, Getting Started                                          Page 10
  581.    STRG String Utilities                           User's Guide, Version 6.1a
  582.  
  583.  
  584.    3.  P H I L O S O P H Y
  585.  
  586.    In this section, you will learn the philosophy behind the development of 
  587.    STRG and how to plan your programming for the highest speeds in string 
  588.    processing.
  589.  
  590.  
  591.    UNIT DESIGN
  592.  
  593.    Identifiers - Since there is an abundance of routines in this unit, 
  594.    remembering the right identifier could be a problem.  But the unit was 
  595.    designed to make it easy with common letters and phrases that are already 
  596.    familiar to you.  All identifiers will have one of the following mnemonics:
  597.  
  598.       Str - for routines that can process both characters and 
  599.             substrings.  The majority of routines have this one to help 
  600.             you correlate the routine with the STRG unit.
  601.       Chr - for an alternative to a Str- routine for processing 
  602.             characters only.
  603.       Wrd - for word parsing routines.
  604.       Is  - for character classification routines.
  605.       Val - for string-to-number conversion routines.
  606.  
  607.    To save space, the documentation will refer to a group of routines using 
  608.    the DOS wildcard characters "*" or "?".  For example, Is* would mean any 
  609.    character classification routine.  In addition, some identifiers also have 
  610.    some common suffixes:
  611.  
  612.       C - means "to center".
  613.       I - means "ignore case".
  614.       L - means "from the left".
  615.       R - means "from the right".
  616.       X - means "indeX".
  617.  
  618.    and if two of them appear together, they will always appear in the order of 
  619.    C-L-R-X-I.
  620.  
  621.    Speed - This unit was specifically designed for speed and every routine has 
  622.    been written in assembly.  These routines easily out perform any similar 
  623.    routines in the Pascal standard library or code written in Pascal.  
  624.    Special techniques have been included to increase speed as much as 
  625.    possible.  The longer the strings, the greater the results can be seen.  
  626. |  When you use STRG, a speed increase of 300% would be typical for 80-char 
  627. |  strings.
  628.  
  629.    Optimization - Almost all routines were placed in separate object files so 
  630.    that the compiler will optimize the code size of your programs.  This may 
  631.    take a second or two longer to compile, but the results are worth it.
  632.  
  633.  
  634.    PROGRAM DESIGN
  635.  
  636.    Procedures vs. Functions - One of the advantages of using a string function 
  637.    is the legibility that it gives the source code.  However, it also comes 
  638.  
  639.  
  640.    Chapter 3, Philosophy                                               Page 11
  641.    STRG String Utilities                           User's Guide, Version 6.1a
  642.  
  643.  
  644.    with the disadvantage of reduced speed from having to make temporary copies 
  645.    in the stack.  The only reason for this is just to make sure that the final 
  646.    destination can handle the final string length.  For long strings, a lot of 
  647.    processing is going on just to check for length limits. 
  648.  
  649.    However, procedures can write directly to the destination and overcome the 
  650.    need for temporary copies.  For this reason, most of the routines in STRG 
  651.    are procedures rather than functions.
  652.  
  653.    Writing Code - If you write your code carefully, you can easily increase 
  654.    your speed by avoiding functions.  For instance, the following code looks 
  655.    very simple:
  656.  
  657.       string1 := string1 + string2;
  658.  
  659.    but in fact it uses functions to achieve the result.  If you use the 
  660.    following code:
  661.  
  662.       StrCat (string1,string2,SizeOf(string1));
  663.  
  664.    you will get the same results, but over 3 times faster!  So, where speed is 
  665.    important, avoid the use of string functions.
  666.  
  667.    Formatting Functions - Yet, there are a few routines that are string 
  668.    functions such as StrJ* and StrHex.  These are final formatting routines 
  669.    that are usually used to provide a final output to screen or disk after 
  670.    most string-intensive processing has been completed.  The resulting strings 
  671.    are usually short as well, so there is not much of a speed reduction 
  672.    making them functions rather than procedures.
  673.  
  674.    Str vs. Chr - Several of the Str* routines like StrQty have built-in 
  675.    routines for processing the special case of a single character just like 
  676.    its counterpart ChrQty.  So there is no need to use both routines.  
  677.    However, if you know that your routines only process characters, then 
  678.    certainly use the Chr* routines as they have a definite speed and code 
  679.    advantage.  This is especially true for ignoring case.  The Chr*I routines 
  680.    analyze each character while Str*I converts the entire string or substring 
  681.    before processing.
  682.  
  683.    Membership vs. Classification - The membership routines are quite fast when 
  684.    the membership substring is relatively short (<15 chars).  If the substring 
  685.    is longer, then it may be faster to consider using the Is* routines or 
  686.    creating your own sets.  Using the rate timer program, RATE61.PAS, included 
  687.    in this package is the best way to tell which one is better for you.
  688.  
  689.    Case Conversion - If you repeatedly use the same string for ignore-case 
  690.    processing, then it would be best to create a temporary string with its 
  691.    case fully converted.  The matching-case routines would then give you a 
  692.    much faster result.  When using either StrLwr or StrUpr, use the one that 
  693.    requires the least amount of conversion in your string.  For example, if 
  694.    your strings are mostly lower case, use the StrLwr routine.  This will 
  695.    increase your speed a few percent.
  696.  
  697.    Pascal vs. C - Although C has the advantage of long length ASCIIZ strings 
  698.  
  699.  
  700.    Chapter 3, Philosophy                                               Page 12
  701.    STRG String Utilities                           User's Guide, Version 6.1a
  702.  
  703.  
  704.    for data storage space, the performance doesn't even come close to Pascal 
  705.    strings with it's calculated length byte.  With STRG and its ASCIIZ 
  706.    conversion routines, you can now have the advantage of both speed and data 
  707.    storage savings.
  708.  
  709.    Alignment - STRG does the most possible to speed up odd-byte alignment of 
  710.    data, but statistically in string moves, some odd-byte alignment will occur 
  711.    which slows the processing down by just a few percent.  However, it is 
  712.    strongly recommended that all string variables be aligned using the $A+ 
  713.    compiler directive.  This can improve your speed about 30%.  If you cannot 
  714.    do this, at least place all of your "even" sized data first in your VAR 
  715.    list and then manually match up the byte size variables with odd size ones 
  716.    so they will self-align.
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.    Chapter 3, Philosophy                                               Page 13
  761.    STRG String Utilities                           User's Guide, Version 6.1a
  762.  
  763.  
  764.    NUMBER TO STRING CONVERSION
  765.  
  766.    Convenience - The Str* number formatting routines such as StrRFD have been 
  767.    provided as a convenience and not for speed improvement.  When you want to 
  768.    knock out code in a hurry and are not concerned with speed, these 
  769.    formatting routines can provide better legibility in your code.  In the 
  770.    long run, they can also save code.  Pascal handily converts numbers into 
  771.    strings with the Str procedure.  For example:
  772.  
  773.      var MyNumber: integer;
  774.          MyString: string;
  775.      begin
  776.        Str (MyNumber:7,MyString);
  777.        Qwik.Qwrite ( 1, 1,SameAttr,MyString);
  778.      end.
  779.  
  780.    But this means that a data area must be reserved and the code isn't as 
  781.    readable as it could be.
  782.  
  783.    Str* Functions - Instead, STRG lets you use a function form of Str:
  784.  
  785.      uses Qwik, Strg;
  786.      var MyNumber: integer;
  787.      begin
  788.        Qwik.Qwrite ( 1, 1,SameAttr,StrLF(MyNumber,7));
  789.      end.
  790.  
  791.    Just like WriteLn, this lets the number remain in the Qwrite statement.  
  792.    The Str* functions actually use the System.Str procedure from to do the 
  793.    conversion.  But these functions were made so that they don't recopy the 
  794.    intermediate string for the greatest speed.  The code usage is also 
  795.    reduced.
  796.  
  797.  
  798. |  NULL STRING INTERPRETATION
  799. |
  800. |  Find - For procedures like StrPosL, STRG handles null strings quite simply 
  801. |  - they are considered to be empty.  For instance:
  802. |
  803. |    MyString := 'abc';
  804. |    i := StrPosL (MyString,'',1);
  805. |  
  806. |  StrPosL is set to find the first occurrence of a null substring in the 
  807. |  string 'abc'.  The variable i would become 0.  The philosophy in STRG is 
  808. |  that you can't find nothing when something is there.  This differs from the 
  809. |  use of Pos which would return 1.  With Pos, the theory is that a null 
  810. |  string is a subset of any string, but we have found that this theory is not 
  811. |  practical for programming with variables that include possible null 
  812. |  strings.  So in STRG, any null string would return the result of 0.
  813. |
  814. |  TP vs. QP - Also be aware that Borland and Microsoft disagree on the 
  815. |  interpretation of the following code:
  816. |
  817. |    i := Pos ('','');
  818.  
  819.  
  820.    Chapter 3, Philosophy                                               Page 14
  821.    STRG String Utilities                           User's Guide, Version 6.1a
  822.  
  823.  
  824. |  
  825. |  In QP, Pos returns 1 while TP returns 0.  Similar parameters for StrPosL 
  826. |  would also return 0 which implies that the index returned cannot be longer 
  827. |  than the length of the searched string.  By returning 1, QP is suggesting 
  828. |  that the two strings are equal which is also a valid observation.  Since 
  829. |  there are no standards like ANSI for this code, we have made just the Pos
  830. |  routine in STRG conform fully to Borland's interpretation.
  831.  
  832.  
  833. |  GREATER SPEEDS
  834. |   
  835. |  You can achieve even greater speeds by using our high-speed SYSTEM unit 
  836. |  replacement unit called SYS60.TPU.  It speeds up some of the internal calls 
  837. |  used by the compiler that otherwise could not be accessed.  The Insert 
  838. |  routine is a good example which has been sped up to 400%.  If you register 
  839. |  for SYS60.ZIP before March 31, 1990  you can receive STRG61A.ZIP for 20% 
  840. |  off the license fee. 
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.    Chapter 3, Philosophy                                               Page 15
  881.    STRG String Utilities                           User's Guide, Version 6.1a
  882.  
  883.  
  884.    A P P E N D I X   A :  O T H E R   P R O D U C T S
  885.  
  886.  
  887.    Eagle Performance Software has developed identical products for Turbo C 
  888.    (TC), Turbo Pascal (TP), Quick C (QC), Microsoft C (MSC), and QuickPascal 
  889.    (QP).  Our pledge is to provide you quality products with unparalleled 
  890.    performance and ease of use.  All registered users receive the complete 
  891. |  source code (except for SYS) when a signed license agreement is returned.
  892.  
  893.  
  894. |  SYS
  895. |
  896. |  SYS - High-speed replacement for your built-in SYSTEM unit.  Speeds up 
  897. |  more than 30 routines.  There is no code to change in your programs.  It's 
  898. |  all built-in, so all you have to do is recompile.  Give your programs a 
  899. |  heart transplant!
  900. |
  901. |    - Longint math - up to 800%
  902. |    - String handling such as Pos, Insert, Delete up to 400%
  903. |    - String/integer conversions - up to 200%.
  904. |    - Drop-in replacement, so there are no code changes to make!
  905. |    - 100% compatible with all your existing code.
  906. |
  907. |  Here are the product versions:
  908. |
  909. |     File name    CIS Name    Compiler 
  910. |     -----------  ----------  ---------
  911. |     SYST55C.ZIP  SYST55.ZIP  TP 5.5
  912. |     SYS60.ZIP    SYS60.ZIP   TP 6.0
  913.  
  914.  
  915.    QWIK
  916.  
  917.    QWIK - For direct screen video, QWIK is the highest performance screen 
  918.    writing tools available today for all text modes in any video 
  919.    configuration.  QWIK provides capabilities far beyond those in the 
  920.    unit/library that comes with your compiler.   Here are some of the 
  921.    features:
  922.                 
  923.      - Writes on all IBM compatible computers, displays and adapters 
  924.        including MDA, CGA, EGA, MCGA, VGA, 8514/A, Hercules and 3270 PC.
  925.      - Superior video detection routine.
  926.      - Eliminates snow and flicker.
  927.      - Writes directly to the screen in absolute rather than relative 
  928.        coordinates.
  929.      - Writes in all text modes and column modes.
  930.      - Writes on all video pages.
  931.      - Writes on virtual screens in RAM.
  932.      - Writes text and attribute, text only, or attribute only.
  933.      - Reads strings, characters and attributes.
  934.      - Uses End-Of-String (EOS) marker for quick string chaining.
  935.      - Provides standardized cursor shapes for all adapters.
  936.      - Enhanced cursor movement.
  937.      - Compatible with DESQview and similar multitasking environments.
  938.  
  939.  
  940.    Appendix A: Other Products                                          Page 16
  941.    STRG String Utilities                           User's Guide, Version 6.1a
  942.  
  943.  
  944.      - Over 650% faster than standard direct screen writing.
  945.      - Only 2.7k bytes of code if all 43 utilities are used.
  946.      - Optimized by the compiler and drops unused code.
  947.      - Used in all other Eagle products.
  948.      - Excellent documentation like this document.
  949.  
  950.    Here are the product versions:
  951.  
  952.       File name    CIS Name    Compiler 
  953.       -----------  ----------  ---------
  954.       QWIK56.ARC   QWIK56.ARC  TP       
  955.       QWIKQ10.ARC  QWKQ10.ARC  QP
  956.       QWIKC20.ARC  QWKC20.ARC  TC/QC/MSC
  957.  
  958.  
  959.    WNDW
  960.  
  961.    WNDW - For multi-level virtual windows, WNDW is the highest performance 
  962.    window utilities available today.  It offers very powerful utilities for 
  963.    full window control and management you probably never thought possible.   
  964.    They are simple and yet very powerful with high speed and tight code.  With 
  965.    WNDW, you can choose the absolute writing routines of QWIK, the window-
  966.    relative writing routines of WNDW, and even customize your own.  Here are 
  967.    some of the features you will discover:
  968.  
  969.      - Uses the powerful direct screen writing routines of QWIK.           
  970.      - Up to 254 fixed or virtual windows can be on the screen at one 
  971.        time.
  972.      - Extremely high-speed virtual screens in RAM (up to 40 times 
  973.        faster).
  974.      - Virtual windows are fully updated on screen, even if covered.  
  975.        Screens can scroll underneath one another right on the screen at 
  976.        very high speeds!       
  977.      - Virtual windows have virtual titles.                                
  978.      - Fully supported hidden windows saved in RAM.                        
  979.      - Fully supports all video pages.                                     
  980.      - Adjustable-rate moving, resizing, and scrolling.                    
  981.      - All windows can be randomly accessed, not just stacked or tiled.    
  982.      - 28 window-relative writing routines.                                
  983.      - 15 different border styles with shadow and zoom effects.            
  984.      - Full line drawing procedures.                                       
  985.      - Full cursor mode control for each window.                           
  986.      - Writes in all text modes and column modes.                          
  987.      - Only 13k bytes of code if all 69 utilities are used.                
  988.      - Used in all other Eagle products.                                   
  989.      - Excellent documentation like this document.
  990.  
  991.    Here are the product versions:
  992.  
  993.       File name    CIS Name    Compiler  
  994.       -----------  ----------  --------  
  995.       WNDW55.ARC   WNDW55.ARC  TP       
  996.       WNDWQ10.ARC  WNDQ10.ARC  QP
  997.       WNDWC20.ARC  WNDC20.ARC  TC/QC/MSC
  998.  
  999.  
  1000.    Appendix A: Other Products                                          Page 17
  1001.    STRG String Utilities                           User's Guide, Version 6.1a
  1002.  
  1003.  
  1004.  
  1005.  
  1006.    PULL
  1007.  
  1008.    PULL - For multi-level pull-down menus, PULL is fully featured and fully 
  1009.    configurable.  Includes execute, single, and multiple choice menus, 
  1010.    unlimited nested submenus, data entry windows, help windows, directory 
  1011.    windows, message system, and fully completed interfaces.  Some of the 
  1012.    features are:
  1013.  
  1014.      - Uses QWIK and WNDW.
  1015.      - Work window(s) and complete interface for menus
  1016.      - Pull-down menus with 3 menu modes and 7 line modes
  1017.      - Pull-down file directory
  1018.      - Highlighted command letters
  1019.      - Unlimited levels of submenus
  1020.      - Unlimited data entry windows for 9 types of data
  1021.      - Data entry for the work window(s)
  1022.         Free field entry with either fixed column or flexible column        
  1023.          length.
  1024.         Full editing capability including insert cursor mode
  1025.         Full field selection with cursor keys
  1026.         Automatic NumLock for numerical data entry
  1027.         Right or left justification for data entry output
  1028.         Error messages for invalid data entries
  1029.         Error messages for data entries out of range
  1030.      - Automatic sizes and locations for menus.
  1031.      - Operation by cursor 
  1032.        keys or command keys
  1033.      - Pull/Pop between work window and nested submenu(s)
  1034.      - Programmable control of pull and pop sequences
  1035.      - Context-sensitive help
  1036.      - Message lines for prompts and processing
  1037.      - Full working shell for user development
  1038.      - Excellent documentation like this document.
  1039.  
  1040.    Here are the product versions:
  1041.  
  1042.       File name    CIS Name    Compiler
  1043.       -----------  ----------  --------
  1044.       PULL55.ARC   PULL55.ARC  TP
  1045.       PULLQ10.ARC  PULQ10.ARC  QP
  1046.       PULLC20.ARC  PULC20.ARC  TC/QC/MSC
  1047.  
  1048.  
  1049.    ON-LINE SERVICES
  1050.  
  1051.    CompuServe - All updated files and later versions can be found on the 
  1052.    CompuServe Borland Forums (GO BPROGA for TP and GO BPROGB for TC) or the 
  1053.    Microsoft Systems Forum (GO MSSYS for QP, QC, and MSC).
  1054.  
  1055.    The Eagle BBS - You can also get the latest files on our 24-hour BBS at 
  1056. |  (214) 539-9878, 1200/2400 N81 and 9600 V.42bis.
  1057.  
  1058.  
  1059.  
  1060.    Appendix A: Other Products                                          Page 18
  1061.    STRG String Utilities                           User's Guide, Version 6.1a
  1062.  
  1063.  
  1064.    A P P E N D I X   B :  R E V I S I O N   H I S T O R Y
  1065.  
  1066.  
  1067.    Version 5.5 (01-02-90):
  1068.      Initial release.
  1069.  
  1070.    Version 5.6 (11-02-90):
  1071.     . Added faster Pos routine to replace System.Pos
  1072.     . Fixed anomaly in Delete and Copy which recognized only byte parameters 
  1073.       in lieu of integer.
  1074.     . Fixed Borland's Delete anomaly when the value of -32768 is used for the 
  1075.       index.  STRG properly does nothing, but Borland's doubles the length of    
  1076.       the string.
  1077.  
  1078.    Version 6.0 (01-02-91):
  1079.     . Recompiled under TP 6.0
  1080.     . Modified docs from 61 to 60 lines per page for laser printers
  1081.     . Added ToPrint.txt for printer instructions.
  1082.     . Made price reductions for most products.
  1083.  
  1084. |  Version 6.1 (01-14-91):
  1085. |   . Added LoCase and UpCase routines.
  1086. |   . Fixed common routine in ChrQtyI, ChrPosLI, ChrPosRI, ChrPosXI, and 
  1087. |     ChrReplI which did not recognize 'A' when 'a' was a parameter.
  1088. |
  1089. |  Version 6.1a (01-23-91):
  1090. |   . Fixed Pos to conform to Borland's interpretation of null strings and 
  1091. |     substrings.  Keep in mind TP6 and Microsoft's QuickPascal do not give 
  1092. |     the same answers:
  1093. |
  1094. |      i := Pos ('','');    { Borland: i=0; Microsoft: i=1 }
  1095. |      j := Pos ('','x');   { j=1 }
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.    Appendix B: Revision History                                        Page 19
  1121.    STRG String Utilities                           User's Guide, Version 6.1a
  1122.  
  1123.  
  1124.    A P P E N D I X   C :  R E F E R E N C E S
  1125.  
  1126.  
  1127.    REFERENCES
  1128.  
  1129.    Trademarks - Turbo Pascal and Turbo C++ are trademarks of Borland 
  1130.    International.  QuickPascal, Quick C, and Microsoft C are trademarks of 
  1131.    Microsoft Corporation.
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.    Appendix C: References                                              Page 20
  1181.